Merging this PR will improve performance by ×2.3

⚡ 9 improved benchmarks
❌ 2 regressed benchmarks
✅ 29 untouched benchmarks
⏩ 80 skipped benchmarks¹

Performance Changes

_{Comparing feat/cycle-estimation (2bc9a1c) with master (fa9ee2e)}

Greptile Summary

This PR adds per-instruction cycle estimation to Callgrind by integrating Capstone for real-time instruction decoding and generated LUT files (x86_caps_lut.inc, arm64_caps_lut.inc) that map packed instruction signatures to throughput and latency centi-cycle costs (Ct/Cl). It is enabled via a new --cycle-estimation=yes flag and wires the costs into the existing event-group framework alongside the cache and branch simulators.

• New decoder pipeline: cycledecode_capstone.c opens a Capstone handle at post_clo_init time with all libc calls forwarded to Valgrind's freestanding coregrind libc; cycledecode.c performs a two-level LUT lookup (exact signature → width-agnostic → per-instruction default → 1.00-cycle flat fallback) and accumulates per-BB running sums for O(1) inclusive-cost updates at side exits.
• Build system: Capstone is now a mandatory build dependency detected by configure.ac; all CI, release, and debian/rules paths switch to --enable-only64bit to avoid compiling the 32-bit secondary target without Capstone. A new composite GitHub Action builds the static Capstone and exports CAPSTONE_DIR.

Confidence Score: 5/5

Safe to merge; both findings are non-blocking edge cases that do not affect the common execution path.

The core decode-and-lookup pipeline, cost accumulation in cachesim_add_icost and setup_bbcc, and the build system wiring are all correct. Both findings are narrow edge cases that do not affect normal amd64/arm64 operation.

callgrind/main.c (zero-length IMark handling) and callgrind/cycledecode_capstone.h (i386 mode guard)

Important Files Changed

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Ist_IMark during CLG_instrument] -->|cycle_estimation=yes, !seen_before| B[clg_cycle_cost bytes from cia len]
    B --> C{cs_disasm_iter Capstone}
    C -->|decode ok| D[compute_sig arch-specific]
    D --> E{row_for exact sig}
    E -->|hit| H[ct_cost = row->cy cl_cost = row->cl]
    E -->|miss| F{row_for width-agnostic}
    F -->|hit| H
    F -->|miss| G{row_for sig==0 default}
    G -->|hit| H
    G -->|miss| I[fallback: 100 centi-cycles]
    C -->|decode fail| I
    H --> J[curr_inode->ct_cost / cl_cost]
    I --> J
    J --> K[BB finalise: compute ct_incl/cl_incl running sums]
    K --> L[Runtime: cachesim_add_icost cost += exe_count x ct_cost]
    K --> M[setup_bbcc side exit cost += ct_incl / cl_incl]

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[Ist_IMark during CLG_instrument] -->|cycle_estimation=yes, !seen_before| B[clg_cycle_cost bytes from cia len]
    B --> C{cs_disasm_iter Capstone}
    C -->|decode ok| D[compute_sig arch-specific]
    D --> E{row_for exact sig}
    E -->|hit| H[ct_cost = row->cy cl_cost = row->cl]
    E -->|miss| F{row_for width-agnostic}
    F -->|hit| H
    F -->|miss| G{row_for sig==0 default}
    G -->|hit| H
    G -->|miss| I[fallback: 100 centi-cycles]
    C -->|decode fail| I
    H --> J[curr_inode->ct_cost / cl_cost]
    I --> J
    J --> K[BB finalise: compute ct_incl/cl_incl running sums]
    K --> L[Runtime: cachesim_add_icost cost += exe_count x ct_cost]
    K --> M[setup_bbcc side exit cost += ct_incl / cl_incl]

_{Reviews (10): Last reviewed commit: "wip: use latest runner to fix samply" | Re-trigger Greptile}

olgtm, do we have internal documentation on how we generated the LUT?
Yes, see AvalancheHQ/valgrind-helpers repository.

• for curiosity: why do we need capstone? It could be made a bit clearer. My understanding is that it's used to transform the instruction's operation to derive the ID for the LUT?

We need to build a LUT for each instruction, but we can't just take the raw bytes as some have 64-bit immediate params. So what we have to extract the parts that identify an instruction. Intel's XED decoder has IFORM which would be super helpful here, as it can identify each instruction by it's category. For example, XED_IFORM_MOV_MEMb_GPR8_DEFINED is mov [reg], reg].

We can't use XED as it's only for x86_64 and not ARM. Which is why we manually reconstruct something similar with Capstone.